Cypress 15 实战

# 1. 安装 Cypress（最新 15.x）
npm install --save-dev cypress

# 2. 首次启动，自动生成配置与脚手架
npx cypress open

# 3. 选择 E2E 或 Component Testing 模式
# 4. 选择浏览器（Chromium / Firefox / Edge）

my-app/
├── cypress/
│   ├── e2e/                 # E2E 测试用例
│   │   └── login.cy.ts
│   ├── component/           # 组件测试用例
│   │   └── Button.cy.tsx
│   ├── fixtures/            # 测试数据（JSON）
│   │   └── user.json
│   ├── support/             # 自定义命令与全局钩子
│   │   ├── commands.ts
│   │   └── e2e.ts
│   └── downloads/           # 下载产物
├── cypress.config.ts        # 全局配置
└── package.json

import { defineConfig } from 'cypress';

export default defineConfig({
  // 文件预处理器：TypeScript / Babel
  e2e: {
    baseUrl: 'http://localhost:5173',     // 被测应用入口
    specPattern: 'cypress/e2e/**/*.cy.ts',
    supportFile: 'cypress/support/e2e.ts',
    viewportWidth: 1280,
    viewportHeight: 720,
    defaultCommandTimeout: 8000,          // 默认命令超时（ms）
    requestTimeout: 10000,
    responseTimeout: 30000,
    video: true,                           // 录制视频
    screenshotOnRunFailure: true,
    // 15.x 新增：多源同源策略白名单
    experimentalWebKitSupport: false,
    setupNodeEvents(on, config) {
      // 插件注册：覆盖率、视觉对比、任务等
      on('task', {
        // 自定义 Node 任务，供 cy.task 调用
        seedDatabase: (fixture) => {
          require('./scripts/seed')(fixture);
          return null;
        },
      });
      return config;
    },
  },
  // 组件测试配置
  component: {
    devServer: {
      framework: 'react',                  // 或 'vue' / 'angular' / 'svelte'
      bundler: 'vite',
    },
    specPattern: 'cypress/component/**/*.cy.{tsx,ts}',
  },
  // Cypress Cloud（可选）
  projectId: 'abc123',
  env: {
    apiUrl: 'https://api.example.com',
    coverage: true,
  },
});

import './commands';

// 全局类型扩展（自定义命令的类型补全）
declare global {
  namespace Cypress {
    interface Chainable {
      loginByApi(email: string, password: string): Chainable<void>;
      dataCy(selector: string): Chainable<JQuery<HTMLElement>>;
    }
  }
}

describe('登录流程', () => {
  beforeEach(() => {
    cy.visit('/login');                    // 访问登录页
  });

  it('使用有效凭证登录成功', () => {
    cy.get('[data-cy=email]')
      .type('user@example.com')            // 输入邮箱
      .should('have.value', 'user@example.com');

    cy.get('[data-cy=password]')
      .type('P@ssw0rd!')
      .type('{enter}');                    // 模拟回车提交

    // 断言路由跳转与欢迎信息
    cy.url().should('include', '/dashboard');
    cy.contains('欢迎回来').should('be.visible');
  });
});

// 1. 状态断言
cy.get('.notification').should('be.visible');
cy.get('.count').should('have.text', '42');

// 2. 类断言
cy.get('button').should('have.class', 'is-loading');

// 3. 多重断言链
cy.get('.user-card')
  .should('be.visible')
  .and('contain', '张三')
  .and('have.attr', 'data-role', 'admin');

// 4. 别名（as）：复用 DOM 引用，避免重复查询
cy.get('.user-list li').eq(0).as('firstUser');
cy.get('@firstUser').should('contain', '张三');
cy.get('@firstUser').find('.role').should('have.text', '管理员');

// 反例：变量赋值失效
let userName;
cy.get('.name').invoke('text').then((text) => {
  userName = text;                          // 仅在回调内可用
});
console.log(userName);                      // undefined —— 命令尚未执行

// 正例：闭包传递
cy.get('.name').invoke('text').then((name) => {
  cy.get('.greeting').should('contain', `你好，${name}`);
});

// 1. 静态 stub：用 fixture 数据替代真实响应
cy.intercept('GET', '/api/users', { fixture: 'users.json' }).as('getUsers');

// 2. 动态 stub：根据请求构造响应
cy.intercept('POST', '/api/login', (req) => {
  const { email, password } = req.body;
  if (email === 'admin@test.com' && password === 'secret') {
    req.reply({ statusCode: 200, body: { token: 'fake-jwt' } });
  } else {
    req.reply({ statusCode: 401, body: { error: 'invalid_credentials' } });
  }
}).as('login');

// 3. 透传并断言请求
cy.intercept('GET', '/api/products', (req) => {
  expect(req.headers['authorization']).to.include('Bearer ');
  req.continue();                            // 放行真实请求
}).as('getProducts');

{
  "data": [
    { "id": 1, "name": "张三", "role": "admin" },
    { "id": 2, "name": "李四", "role": "member" }
  ]
}

// 模拟慢速网络（3 秒延迟）
cy.intercept('GET', '/api/dashboard', (req) => {
  req.reply({ delay: 3000, fixture: 'dashboard.json' });
}).as('slowDashboard');

// 模拟 502 网关错误
cy.intercept('GET', '/api/orders', { statusCode: 502, body: 'Bad Gateway' });

// 等待拦截请求并断言请求体
cy.visit('/dashboard');
cy.wait('@slowDashboard').its('request.url').should('include', '/dashboard');

// cypress/support/commands.ts
Cypress.Commands.add('loginByApi', (email: string, password: string) => {
  cy.request('POST', `${Cypress.env('apiUrl')}/auth/login`, { email, password })
    .then((res) => {
      cy.window().then((win) => {
        win.localStorage.setItem('token', res.body.token);
      });
    });
});

Cypress.Commands.add('dataCy', (selector: string) => {
  return cy.get(`[data-cy=${selector}]`);
});

Cypress.Commands.add('resetDb', () => {
  cy.task('seedDatabase', 'test-fixture');
});

beforeEach(() => {
  cy.session('admin-user', () => {
    cy.loginByApi('admin@test.com', 'secret');
  });
});

it('查看仪表盘', () => {
  cy.visit('/dashboard');                   // 自动复用 session，无需重新登录
  cy.dataCy('metric-total').should('be.visible');
});

// 1. 视觉回归（cypress-image-snapshot）
describe('首页视觉回归', () => {
  it('桌面视口截图应与基线一致', () => {
    cy.visit('/');
    cy.matchImageSnapshot('home-desktop', {
      failureThreshold: 0.03,            // 容忍 3% 像素差异
      failureThresholdType: 'percent',
    });
  });
});

// 2. 无障碍扫描（cypress-axe）
describe('无障碍合规检查', () => {
  it('登录页应通过 axe 扫描', () => {
    cy.visit('/login');
    cy.injectAxe();                       // 注入 axe-core
    cy.checkA11y(undefined, {
      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] },
    });
  });

  it('忽略已知容差节点', () => {
    cy.checkA11y({
      exclude: ['.ad-banner', '[data-cy=legacy-widget]'],
    });
  });
});

// cypress/component/Button.cy.tsx
import { mount } from '@cypress/react18';
import { Button } from '@/components/Button';

describe('Button 组件', () => {
  it('点击触发 onClick 回调', () => {
    const onClick = cy.stub().as('onClick');
    mount(<Button onClick={onClick}>提交</Button>);
    cy.get('button').click();
    cy.get('@onClick').should('have.been.calledOnce');
  });

  it('disabled 状态阻止点击', () => {
    const onClick = cy.stub();
    mount(<Button disabled onClick={onClick}>提交</Button>);
    cy.get('button').should('be.disabled').click({ force: true });
    cy.wrap(onClick).should('not.have.been.called');
  });
});

// cypress/component/Counter.cy.ts
import { mount } from '@cypress/vue';
import Counter from '@/components/Counter.vue';

describe('Counter 组件', () => {
  it('点击自增', () => {
    mount(Counter);
    cy.get('button').click().click();
    cy.get('.count').should('have.text', '2');
  });
});

# Headless 运行全部 E2E 用例
npx cypress run

# 指定浏览器
npx cypress run --browser chrome

# 仅运行 Component Testing
npx cypress run --component

# 按 tag 筛选用例（依赖 @cypress/grep）
npx cypress run --env grepTags=@smoke

# 生成 JUnit 报告
npx cypress run --reporter junit --reporter-options "mochaFile=results/test-output.xml"

name: E2E
on: [pull_request]
jobs:
  cypress-run:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        # 4 台并行机器
        containers: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: cypress-io/github-action@v6
        with:
          start: npm run dev
          wait-on: 'http://localhost:5173'
          record: true
          parallel: true
          browser: chrome
        env:
          # Cypress Cloud 凭证（启用并行编排与失败分析）
          CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
          CYPRESS_PROJECT_ID: ${{ secrets.CYPRESS_PROJECT_ID }}